docs: added tax-inclusive conceptual guide and updates to storefront guide (#8186)

* docs: added tax-inclusive conceptual guide and updates to storefront guide

* sentence fix

* currency_code -> country_code

www/apps/resources/app/commerce-modules/pricing/price-calculation/page.mdx

@@ -1,7 +1,7 @@
 import { Tabs, TabsList, TabsTrigger, TabsContent, TabsContentWrapper, TypeList } from "docs-ui"
 
 export const metadata = {
-  title: `Prices Calculation Strategy`,
+  title: `Prices Calculation`,
 }
 
 # {metadata.title}
@@ -77,6 +77,16 @@ Both prices are returned in an object along with the following properties:
       type: "`string`",
       description: "The currency code of the calculated price, or `null` if there isn't a calculated price."
     },
+    {
+      name: "is_calculated_price_tax_inclusive",
+      type: "`boolean`",
+      description: "Whether the calculated price is tax inclusive. Learn more about tax-inclusivity in [this document](../tax-inclusive-pricing/page.mdx)"
+    },
+    {
+      name: "is_original_price_tax_inclusive",
+      type: "`boolean`",
+      description: "Whether the original price is tax inclusive. Learn more about tax-inclusivity in [this document](../tax-inclusive-pricing/page.mdx)"
+    },
     {
       name: "calculated_price",
       type: "`object`",
@@ -224,6 +234,9 @@ const priceSet = await pricingModuleService.createPriceSets({
 
       currency_code: "EUR",
 
+      is_calculated_price_tax_inclusive: false,
+      is_original_price_tax_inclusive: false,
+
       calculated_price: {
         price_id: "<DEFAULT_PRICE_ID>",
         price_list_id: null,
@@ -288,6 +301,9 @@ const priceSet = await pricingModuleService.createPriceSets({
 
       currency_code: "EUR",
 
+      is_calculated_price_tax_inclusive: false,
+      is_original_price_tax_inclusive: false,
+
       calculated_price: {
         price_id: "<FOURTH_PRICE_ID>",
         price_list_id: null,
@@ -375,6 +391,9 @@ const priceSet = await pricingModuleService.createPriceSets({
 
       currency_code: "EUR",
 
+      is_calculated_price_tax_inclusive: false,
+      is_original_price_tax_inclusive: false,
+
       calculated_price: {
         price_id: "<FOURTH_PRICE_ID>",
         price_list_id: null,

www/apps/resources/app/commerce-modules/pricing/tax-inclusive-pricing/page.mdx

@@ -0,0 +1,74 @@
+export const metadata = {
+  title: `Tax-Inclusive Pricing`,
+}
+
+# {metadata.title}
+
+In this document, you’ll learn about tax-inclusive pricing and how it's used during prices calculation.
+
+## What is Tax-Inclusive Pricing?
+
+A tax-inclusive price is a price that includes taxes. The tax amount is calculated from the price rather than added to it.
+
+For example, if a product’s price is $50 and the tax rate is 2%, then the tax-inclusive price is $49, and the applied tax amount is $1.
+
+---
+
+## How is Tax-Inclusive Pricing Set?
+
+The `PricePreference` data model holds the tax-inclusive setting for a context. It has two properties that indicate the context:
+
+- `attribute`: The name of the attribute to compare against. For example, `region_id` or `currency_code`.
+- `value`: The attribute’s value. For example, `reg_123` or `usd`.
+
+<Note>
+
+Only `region_id` and `currency_code` are supported as an `attribute` at the moment.
+
+</Note>
+
+The `is_tax_inclusive` property indicates whether tax-inclusivity is enabled in the specified context.
+
+For example:
+
+```json
+{
+  "attribute": "currency_code",
+  "value": "USD",
+  "is_tax_inclusive": true,
+}
+```
+
+In this example, tax-inclusivity is enabled for the `USD` currency code.
+
+---
+
+## Tax-Inclusive Pricing in Price Calculation
+
+### Tax Context
+
+As mentioned in the [Price Calculation documentation](../price-calculation/page.mdx#calculation-context), The `calculatePrices` method accepts as a parameter a calculation context.
+
+To get accurate tax results, pass the `region_id` and / or `currency_code` in the calculation context.
+
+### Returned Tax Properties
+
+The `calculatePrices` method returns two properties related to tax-inclusivity:
+
+- `is_calculated_price_tax_inclusive`: Whether the selected `calculated_price` is tax-inclusive.
+- `is_original_price_tax_inclusive` : Whether the selected `original_price` is tax-inclusive.
+
+A price is considered tax-inclusive if:
+
+1. It belongs to the region or currency code specified in the calculation context;
+2. and the region or currency code has a price preference with `is_tax_inclusive` enabled.
+
+### Tax Context Precedence
+
+If:
+
+- both the `region_id` and `currency_code` are provided in the calculation context;
+- the selected price belongs to the region;
+- and the region has a price preference
+
+Then, the region’s price preference’s `is_tax_inclusive`'s value takes higher precedence in determining whether a price is tax-inclusive.