chore: improvements to provider docs (#11451)

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/fulfillment-provider.ts

@@ -22,6 +22,12 @@ const fulfillmentProviderOptions: FormattingOptionsType = {
       reflection_typeParameters: false,
     },
     startSections: [
+      `## Understanding Fulfillment Provider Implementation
+
+The Fulfillment Module Provider handles processing fulfillments and shipments with a third-party provirder. However, it's not responsible for managing fulfillment concepts within Medusa, such as creating a fulfillment or its shipments. The Fulfillment Module uses your fulfillment provider within core operations.
+
+For example, when the merchant creates a fulfillment for an order, the Fulfillment Module uses your fulfillment provider to create the fulfillment in the third-party system, then creates the fulfillment in Medusa. So, you only have to implement the third-party fulfillment processing logic in your fulfillment provider.
+`,
       `## 1. Create Module Provider Directory
 
 Start by creating a new directory for your module provider.

www/utils/packages/typedoc-generate-references/src/constants/merger-custom-options/payment-provider.ts

@@ -22,6 +22,12 @@ const paymentProviderOptions: FormattingOptionsType = {
       reflection_typeParameters: false,
     },
     startSections: [
+      `## Understanding Payment Provider Implementation
+
+The Payment Module Provider handles processing payment with a third-party provirder. However, it's not responsible for managing payment concepts within Medusa, such as payment sessions or collections. These concepts are handled by the Payment Module which uses your payment provider within core operations.
+
+For example, when the merchant captures an order's payment, the Payment Module uses the payment provider to capture the payment, the makes updates to the \`Payment\` record associated with the order. So, you only have to implement the third-party payment processing logic in your payment provider.
+`,
       `## 1. Create Module Provider Directory
 
 Start by creating a new directory for your module provider.