feat: add price_treatment to the price type

[YanisMtcr]

Context: #256 (LATAM pricing) raised the same class of issue. This scopes it to the catalog price marker.

---

price_treatment is a new optional object on the price type, scoped to tax for now: tax.inclusion states whether the amount includes tax (VAT, GST, etc.), as one of included, excluded, not_applicable, not_asserted. A catalog price already carries amount and currency; today it never says whether tax is in it, so an agent has to infer that from the buyer's country. This makes the price self-describing, mirroring how currency is already explicit, and the container leaves room for tax detail later without adding sibling fields to price.

What it looks like

A tax-inclusive EU catalog price:

{ "amount": 12000, "currency": "EUR", "price_treatment": { "tax": { "inclusion": "included" } } }

A US catalog price omits it (or sets excluded); tax is added downstream. The itemized tax breakdown stays in checkout totals; this field only disambiguates the displayed price.

Optional and backward-compatible: an absent field is equivalent to not_asserted, behavior is unchanged; agents that ignore it fall back to today's inference, agents that read it drop the guesswork.

Category (Required)

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)

Checklist

• I have followed the Contributing Guide (Conventional Commits title, no breaking changes).
• I have updated the documentation.
• cspell and markdownlint pass locally. ucp-schema and super-linter not run locally (no cargo/docker); relying on CI.
• I have added tests that prove my fix is effective or that my feature works.
• (For Core/Capability) I have included/updated the relevant JSON schemas.
• I have regenerated Python Pydantic models by running generate_models.sh under python_sdk. Not applicable, no Python SDK in this repo yet.

[karangoel16]

I think this should be modeled as an object rather than a boolean on price.

tax_included: true/false solves the immediate display ambiguity, but it gives us little room for future cases like not applicable, not asserted, partially included, estimated tax, or tax-specific details. false also becomes overloaded: excluded vs unknown vs not applicable.

Could we use a broader container and scope the first version to tax? For example:

"price_treatment": {
  "$ref": "#/$defs/price_treatment"
}

with:

"price_treatment": {
  "type": "object",
  "description": "How the price amount should be interpreted for display and downstream calculation.",
  "properties": {
    "tax": {
      "$ref": "#/$defs/tax_treatment"
    }
  }
}

"tax_treatment": {
  "type": "object",
  "required": ["inclusion"],
  "properties": {
    "inclusion": {
      "type": "string",
      "enum": ["included", "excluded", "not_applicable", "not_asserted"]
    }
  }
}

That keeps this PR scoped to the current tax-inclusion problem, while giving the protocol a place to add tax-specific detail later without adding more sibling booleans to price.

[YanisMtcr]

Agreed, the enum removes the false ambiguity and the container leaves room for tax detail later. Updated to this shape: price_treatment and tax_treatment are new common types referenced from price, following the one-file-per-type convention rather than inline $defs, scoped to tax.inclusion for now. The docs now state that an absent field is equivalent to not_asserted and that the itemized totals breakdown stays authoritative during checkout. PR title updated to match.