[IMP] Taxes: fix tax computation / included in price

task-5094417

At the moment, the section for the `Percentage of Price tax included`
tax computation doesn't distinguish itself enough from the 'Included in
Price' option which people usually want.

Percentage of Price Tax Included taxes are very rare and only used in
countries where tax rates are expressed as a percentage of the
tax-included total.

We also take the opportunity to improve the description of the
`Percentage of Price` computation type and the `Included in Price`
option.

Author: antoine162

content/applications/finance/accounting/taxes.rst

@@ -72,23 +72,38 @@ The **tax name** is displayed for backend users in the :guilabel:`Taxes` field i
 Tax computation
 ~~~~~~~~~~~~~~~
 
-- **Group of Taxes**
+The :guilabel:`Tax Computation` field determines how the tax amount is computed from the sales
+price. The following options are available:
+
+- :ref:`taxes/computation/group-of-taxes`: a combination of several other taxes
+- :ref:`taxes/computation/fixed`: a fixed amount
+- :ref:`taxes/computation/percentage-of-price`: a percentage of the tax-excluded sales price
+- :ref:`taxes/computation/percentage-of-price-tax-included`: a percentage of the tax-included total
+- :ref:`taxes/computation/python-code`: a custom user-defined formula.
+
+.. _taxes/computation/group-of-taxes:
+
+Group of Taxes
+**************
 
   The tax is a combination of multiple sub-taxes. You can add as many taxes as you want, in the
   order you want them to be applied.
 
-  .. important::
-     Make sure that the tax sequence is correct, as the order in which they are may impact the
-     taxes' amounts computation, especially if one of the taxes :ref:`affects the base of the
-     subsequent ones <taxes/base-subsequent>`.
+.. important::
+   Make sure that the tax sequence is correct, as the order in which they are may impact the
+   taxes' amounts computation, especially if one of the taxes :ref:`affects the base of the
+   subsequent ones <taxes/base-subsequent>`.
+
+.. _taxes/computation/fixed:
 
-- **Fixed**
+Fixed
+*****
 
-  The tax has a fixed amount in the default currency. The amount remains the same, regardless of the
-  sales price.
+The tax has a fixed amount in the default currency. The amount remains the same, regardless of the
+sales price.
 
 .. example::
-   A product has a sales price of $1000, and we apply a $10 *fixed* tax. We then have:
+   A product has a sales price of $1000, and we apply a $10 fixed tax. We then have:
 
    +-------------+-------------+----------+----------+
    | Product     | Price       | Tax      | Total    |
@@ -97,42 +112,115 @@ Tax computation
    | 1,000       | 1,000       | 10       | 1,010.00 |
    +-------------+-------------+----------+----------+
 
-- **Percentage of price**
+.. _taxes/computation/percentage-of-price:
 
-  The *sales price* is the taxable basis: the tax amount is computed by multiplying the sales price
-  by the tax percentage.
+Percentage of Price
+*******************
 
-.. example::
-   A product has a sales price of $1000, and we apply a *10% of Price* tax. We then have:
+The tax rate is a percentage of the **tax-excluded** subtotal.
 
-   +-------------+-------------+----------+----------+
-   | Product     | Price       | Tax      | Total    |
-   | sales price | without tax |          |          |
-   +=============+=============+==========+==========+
-   | 1,000       | 1,000       | 100      | 1,100.00 |
-   +-------------+-------------+----------+----------+
+The exact tax computation depends on the :ref:`taxes/included-in-price` field, which determines
+whether the sales price should be treated as tax-excluded or tax-included:
 
-- **Percentage of Price Tax Included**
+.. tabs::
+   .. tab:: Tax-excluded
 
-  The **total** is the taxable basis: the tax amount is a percentage of the total.
+      If :guilabel:`Included in Price` is unchecked, the computation is :math:`\text{tax amount}
+      = \text{sales price} \times \text{tax rate}`.
 
-.. example::
-   A product has a Sales Price of $1000, and we apply a *10% of Price Tax Included* tax. We then
-   have:
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax that is not :guilabel:`Included in Price`. We then have:
 
-   +-------------+-------------+----------+----------+
-   | Product     | Price       | Tax      | Total    |
-   | sales price | without tax |          |          |
-   +=============+=============+==========+==========+
-   | 1,000       | 1,000       | 111.11   | 1,111.11 |
-   +-------------+-------------+----------+----------+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 1,000       | 100      | 1,100.00 |
+         +-------------+-------------+----------+----------+
+
+   .. tab:: Tax-included
+
+      If :guilabel:`Included in Price` is checked, the computation is :math:`\text{tax amount} =
+      \text{sales price} \times \frac{\text{tax rate}}{1 + \text{tax rate}}`.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price`
+         tax that is :guilabel:`Included in Price`. We then have:
+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 909.09      | 90.91    | 1,000.00 |
+         +-------------+-------------+----------+----------+
+
+.. _taxes/computation/percentage-of-price-tax-included:
+
+Percentage of Price Tax Included
+********************************
+
+The tax rate is a percentage of the **tax-included** total.
+
+The exact tax computation depends on the :ref:`taxes/included-in-price` field, which determines
+whether the sales price should be treated as tax-excluded or tax-included:
+
+.. tabs::
+   .. tab:: Tax-excluded
+      If :guilabel:`Included in Price` is unchecked, the computation is :math:`\text{tax amount}
+      = \text{sales price} \times \frac{\text{tax rate}}{1 - \text{tax rate}}`.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price
+         Tax Included` tax that is not :guilabel:`Included in Price`. We then have:
+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 1,000       | 111.11   | 1,111.11 |
+         +-------------+-------------+----------+----------+
+
+         Note that the real tax rate in terms of the tax-excluded price is
+         :math:`\frac{111.11}{1000} = 11.111\%`.
+
+   .. tab:: Tax-included
+
+      If :guilabel:`Included in Price` is checked, the computation is :math:`\text{tax amount} =
+      \text{sales price} \times \text{tax rate}`.
+
+      .. example::
+         A product has a sales price of $1000, and we apply a 10%
+         :guilabel:`Percentage of Price Tax Included` tax that is :guilabel:`Included in Price`.
+         We then have:
+
+         +-------------+-------------+----------+----------+
+         | Product     | Price       | Tax      | Total    |
+         | sales price | without tax |          |          |
+         +=============+=============+==========+==========+
+         | 1,000       | 900         | 100      | 1,000.00 |
+         +-------------+-------------+----------+----------+
+
+         Note that the real tax rate in terms of the tax-excluded price is
+         :math:`\frac{100}{900} = 11.111\%`.
+
+.. warning::
+   This tax computation is rarely used and only useful in countries (e.g. Brazil, Bolivia) that
+   quote tax rates as a percentage of the tax-included total.
+   For the more common need to compute tax amounts from a tax-included price, use the
+   :ref:`taxes/computation/percentage-of-price` tax computation with the
+   :ref:`taxes/included-in-price` option.
+
+.. _taxes/computation/python-code:
 
-- **Python code**
+Python code
+***********
 
-  A tax defined as **Python code** consists of two snippets of Python code that are executed in a
-  local environment containing data such as the unit price, product or partner.
-  :guilabel:`Python Code` defines the amount of the tax, and :guilabel:`Applicable Code` defines if
-  the tax is to be applied. The formula is found at the bottom of the :guilabel:`Definition` tab.
+A tax defined as **Python code** consists of two snippets of Python code that are executed in a
+local environment containing data such as the unit price, product or partner.
+:guilabel:`Python Code` defines the amount of the tax, and :guilabel:`Applicable Code` defines if
+the tax is to be applied. Enter a formula for each field at the bottom of the
+:guilabel:`Definition` tab.
 
 .. example::
    :guilabel:`Python Code`: `result = price_unit * 0.10`
@@ -256,24 +344,27 @@ invoice line.
 Included in price
 ~~~~~~~~~~~~~~~~~
 
-With this option activated, the total (including the tax) equals the **sales price**.
+With this option activated, the tax will treat the sales price on which it is applied as a total
+including the tax amount. The tax computation will split the sales price into a base amount and a
+tax amount. This makes it suitable for B2C sales in most countries where prices are quoted
+tax-inclusive.
 
 `Total = Sales Price = Computed Tax-Excluded price + Tax`
 
 .. example::
-   A product has a sales price of $1000, and we apply a *10% of Price* tax, which is *included in
-   the price*. We then have:
+   A product has a sales price of $1000, and we apply a 10% :guilabel:`Percentage of Price` tax
+   with :guilabel:`Included in Price` checked. We then have:
 
    +-------------+-------------+----------+----------+
    | Product     | Price       | Tax      | Total    |
    | sales price | without tax |          |          |
    +=============+=============+==========+==========+
-   | 1,000       | 900.10      | 90.9     | 1,000.00 |
+   | 1,000       | 909.09      | 90.91    | 1,000.00 |
    +-------------+-------------+----------+----------+
 
 .. note::
-   If you need to define prices accurately, both tax-included and tax-excluded, please refer to the
-   following documentation: :doc:`taxes/B2B_B2C`.
+   For a guide on configuring tax-excluded and tax-included prices for B2B and B2C customers,
+   see :doc:`taxes/B2B_B2C`.
 
 .. note::
    By default, only the :guilabel:`Tax excluded` column is displayed on invoices. To display the