Add firm-level VAT planning docs page (#1320 #1333)

[vahid-ahmadi]

Summary

• Add firm-level VAT logic with new Firm entity #1320 and Add firm analysis files #1333 are filed as planning trackers for adding firm-level VAT to PolicyEngine UK. Persist the plan in-repo as a "planned: not yet modelled" page mirroring the BiK plan added in Plan: model benefits-in-kind (BiK) — scope, implementation, and data needs #1654, so future work has a stable reference rather than a moving issue body.
• New page at docs/book/programs/gov/hmrc/firm-vat.md covering:
  • Why firm-level VAT — household-side VAT (vat variable) can't answer questions about registration thresholds, supplier-side rate changes, or the flat-rate scheme.
  • Phase 1 MVP scope — Firm entity, registration threshold logic (currently £90,000), sector-driven standard/reduced/zero/exempt supply split, and firm_vat_on_sales / firm_vat_on_purchases / firm_net_vat_liability.
  • Phases 2 & 3 — flat-rate scheme, VAT groups, partial exemption; eventually firm-to-household incidence linking through to consumer prices.
  • Proposed Firm entity definition in entities.py, with a note that it deliberately doesn't contain household (sole traders link via input variable; incorporated firms have no household).
  • Variables and parameters trees under gov/hmrc/vat/firm/.
  • Data gap and synthetic-firm-panel imputation approach consistent with Align UK model/data pipeline with US patterns: reported-anchoring, second-stage imputation, and downstream bugs #1621's second-stage pattern, with the panel owned by policyengine-uk-data and rules variables here.
  • Effort estimate and open questions (panel location, MTD mechanics, HMRC Datalab access).
• Cross-references the companion analysis repo policyengine/uk-vatlab (Add firm analysis files #1333).

When the MVP lands the "planned" warning at the top is dropped and the page becomes the live firm-VAT docs.

Test plan

• Markdown lints cleanly (tables, code block for the entity stub, MyST {warning} admonition).
• Docs build job picks up the new page under programs/gov/hmrc/.

🤖 Generated with Claude Code