Document pension tax relief mechanics (#704)

[vahid-ahmadi]

Summary

• Pension tax relief calculations #704 reported four worked scenarios where the user expected higher-rate pension contributions to produce only basic-rate (20%) income-tax relief but the model returned full marginal-rate (40%) reductions.
• Investigation: the model is correct. The reported numbers match HMRC's treatment in aggregate (relief-at-source + higher-rate top-up via Self Assessment combined). The user's mental model only counted the first half.
• New docs page at docs/book/programs/gov/hmrc/pension-tax-relief.md covering:
  • how pension_contributions_relief works (reduces taxable income £1-for-£1 up to the annual allowance / basic amount / earned income cap),
  • the four Pension tax relief calculations #704 scenarios with PolicyEngine's exact returns and the marginal-rate arithmetic that produces them,
  • the two-part real-world mechanism (RAS + basic-rate-band extension) and why PolicyEngine reports the combined total (matches HMRC's pension tax relief statistics methodology),
  • a note that the 0% marginal-tax-rate display the user observed is a frontend concern in the policyengine.org app, not the model repo,
  • references to FA 2004 s.188-194 and s.227, the HMRC user-facing pension tax relief guide, and HMRC pension tax relief statistics.

Pure documentation; no code changes. #704 can be closed.

Test plan

• Markdown lints cleanly (table, links, MyST elements).
• Docs build job picks up the new page under programs/gov/hmrc/.

🤖 Generated with Claude Code