Tax Withholding Data Model

1. Executive Summary

Purpose

The tax withholding data model supports the calculation, application, auditing, and regulatory reporting of withholding taxes on payments made to talent and their parties. It sits downstream of the billing and cash receipt domains: when a worksheet applies cash against a PAY receivable, the tax engine evaluates the party's tax profile, determines applicable jurisdiction rules, calculates withholding amounts, and records the results for compliance filing.

Billing Item (receivable established)
  --> Cash Receipt arrives
    --> Worksheet applies cash to PAY receivable
      --> Tax engine evaluates party_tax_info + tax_rate_config
        --> Withholding deduction created on application
          --> tax_calculation_audit records full calculation snapshot
            --> tax_form generated for regulatory filing
              --> tax_filing_package groups forms for submission

Scope

Covered:

party_tax_info — Master tax profile per party: residency, TIN, VAT registration, W-8/W-9, CWA, and treaty status
tax_rate_config — Configurable tax rates and thresholds per jurisdiction and tax type, effective-dated
tax_calculation_audit — Immutable audit trail of every tax calculation with full input/output snapshots
tax_form — Individual tax forms (IRS 1042-S, HMRC FEU1/FEU2, etc.) with status tracking
tax_filing_package — Groups related tax forms into a filing unit (e.g., IRS 1042 annual package)

Not covered (documented separately):

Worksheet application flow — see Worksheets Data Model
Billing item structure — see Billing Items Data Model
Settlement and payout mechanics — see Settlements Data Model
Cash receipt split flow — see Cash Receipts Data Model

2. Data Model

2.1 Entity-Relationship Diagram

mermaid

erDiagram
    party ||--o{ party_tax_info : "has tax profiles"
    party_tax_info ||--o{ tax_calculation_audit : "snapshot captured in"
    tax_rate_config ||--o{ tax_calculation_audit : "snapshot captured in"
    party ||--o{ tax_form : "subject of"
    tax_filing_package ||--o{ tax_form : "groups"
    users ||--o{ tax_calculation_audit : "calculated by"
    users ||--o{ tax_form : "created/updated by"
    users ||--o{ tax_filing_package : "created/updated by"

    party_tax_info {
        serial party_tax_info_id PK
        integer party_id FK
        varchar tax_residence_cd
        varchar entity_type_cd
        varchar tin_type_cd
        varchar tin_number
        boolean vat_registered_ind
        varchar vat_number
        boolean has_w9_on_file_ind
        boolean has_w8_on_file_ind
        varchar w8_form_type_cd
        date w8_expiration_dt
        boolean has_cwa_approval_ind
        date cwa_expiration_dt
        decimal cwa_withholding_amt
        boolean has_tax_treaty_ind
        varchar treaty_country_cd
        date effective_from_dt
        date effective_to_dt
        boolean current_item_ind
    }

    tax_rate_config {
        serial tax_rate_config_id PK
        varchar jurisdiction_cd
        varchar tax_type_cd
        decimal rate
        decimal threshold_amt
        varchar currency_cd
        date effective_from_dt
        date effective_to_dt
    }

    tax_calculation_audit {
        serial tax_calculation_audit_id PK
        varchar context_type_cd
        integer context_id
        jsonb input_json
        jsonb result_json
        jsonb party_tax_info_snapshot_json
        jsonb rate_config_snapshot_json
        integer calculated_by_user_id FK
        timestamp calculated_dt
    }

    tax_form {
        serial tax_form_id PK
        integer party_id FK
        varchar party_name
        varchar form_code_cd
        varchar jurisdiction_cd
        integer tax_year
        varchar quarter_cd
        varchar status_cd
        timestamp generated_dt
        timestamp filed_dt
        jsonb form_data_json
        jsonb source_map_json
        varchar source_type_cd
        integer source_id
        integer tax_filing_package_id FK
        varchar mailing_cd
        varchar chapter_cd
        integer sequence_no
        varchar notes
    }

    tax_filing_package {
        serial tax_filing_package_id PK
        integer tax_year
        varchar jurisdiction_cd
        varchar filing_type_cd
        varchar status_cd
        timestamp generated_dt
        timestamp filed_dt
        jsonb reconciliation_json
        varchar notes
    }

2.2 `party_tax_info`

Master data table for party-level tax profiles. Each party can have multiple profiles over time through effective dating, with exactly one marked as current. This table is the primary input to the withholding tax engine — it determines whether withholding applies, which jurisdiction rules to invoke, and which tax forms are required.

Field	Type	Required	Default	Description
`party_tax_info_id`	`serial`	Yes	Auto	Primary key.
`party_id`	`integer`	Yes	—	FK to `party.party_id`. A party can have multiple tax info records over time.
`tax_residence_cd`	`varchar(10)`	No	—	ISO country code indicating tax residence: `US`, `GB`, `CA`, `JP`, `FR`, etc. Drives jurisdiction rule selection.
`entity_type_cd`	`varchar(30)`	No	—	Legal entity classification. See Code Master Values. Affects withholding applicability and form requirements.
`tin_type_cd`	`varchar(20)`	No	—	Tax identification number type. See Code Master Values.
`tin_number`	`varchar(50)`	No	—	Tax identification number. Masked in all user-facing displays.
`vat_registered_ind`	`boolean`	Yes	`false`	Whether the party is registered for UK VAT. When `true`, 20% VAT applies to artist fees and commissions on qualifying UK transactions.
`vat_number`	`varchar(50)`	No	—	UK VAT registration number. Required when `vat_registered_ind = true`.
`has_w9_on_file_ind`	`boolean`	Yes	`false`	Whether a W-9 form is on file. Indicates US person status for 1099-NEC reporting.
`has_w8_on_file_ind`	`boolean`	Yes	`false`	Whether a W-8 form is on file. Required for non-resident aliens receiving US-source income.
`w8_form_type_cd`	`varchar(20)`	No	—	Specific W-8 form variant. See Code Master Values.
`w8_expiration_dt`	`date`	No	—	W-8 form expiration date. System generates expiring-document alerts as this date approaches.
`has_cwa_approval_ind`	`boolean`	Yes	`false`	Whether an IRS Central Withholding Agreement is in effect. When `true`, the CWA amount overrides the default 30% NRA rate.
`cwa_expiration_dt`	`date`	No	—	CWA expiration date. System generates expiring-document alerts as this date approaches.
`cwa_withholding_amt`	`decimal(15,2)`	No	—	IRS-approved flat withholding dollar amount per engagement. Set by the IRS based on estimated net income and graduated tax rates.
`has_tax_treaty_ind`	`boolean`	Yes	`false`	Whether the party claims a tax treaty exemption. When `true`, withholding may be reduced to 0% (Form 8233 required).
`treaty_country_cd`	`varchar(10)`	No	—	ISO country code of the treaty partner country.
`effective_from_dt`	`date`	No	—	Start date for this tax profile version.
`effective_to_dt`	`date`	No	—	End date for this tax profile version. `null` indicates the profile has no defined end date.
`current_item_ind`	`boolean`	Yes	`true`	Indicates whether this is the active tax profile for the party. Only one record per party should have `current_item_ind = true` at any time.

IMPORTANT

The cwa_withholding_amt field represents a flat dollar amount approved by the IRS, not a rate. When a CWA is in effect (has_cwa_approval_ind = true) but cwa_withholding_amt is null or zero, the system withholds $0 and raises a compliance alert warning that the CWA amount has not been configured.

WARNING

The tin_number field contains sensitive personally identifiable information (PII). It must be masked in all user-facing displays and access-logged in audit trails. The raw value is only used for regulatory form generation.

NOTE

Pure audit columns (created_by, created_dt, updated_by, updated_dt) are omitted from the table above as they carry no business meaning beyond standard record-keeping.

2.3 `tax_rate_config`

Configuration-driven tax rates per jurisdiction and tax type. Replaces hardcoded rate constants, enabling rate changes without code deployment. All rates are effective-dated to support tax year transitions (e.g., UK personal allowance changes annually on April 6, US NRA rate could change with legislation).

Field	Type	Required	Default	Description
`tax_rate_config_id`	`serial`	Yes	Auto	Primary key.
`jurisdiction_cd`	`varchar(10)`	Yes	—	Jurisdiction code: `US`, `GB`. Must match a supported jurisdiction.
`tax_type_cd`	`varchar(50)`	Yes	—	Tax type within the jurisdiction. See Code Master Values for valid codes.
`rate`	`decimal(7,4)`	No	—	Tax rate as a decimal fraction. Example: `0.3000` = 30%, `0.2000` = 20%.
`threshold_amt`	`decimal(15,2)`	No	—	Monetary threshold for rate applicability. Used for the UK personal allowance (currently `12570.00` GBP).
`currency_cd`	`varchar(3)`	No	—	Currency of the threshold amount. Required when `threshold_amt` is set. Example: `GBP` for UK personal allowance.
`effective_from_dt`	`date`	Yes	—	Start date for this rate configuration. Tax rates are looked up by finding the config whose effective date range contains the transaction date.
`effective_to_dt`	`date`	No	—	End date for this rate configuration. `null` indicates the rate has no defined end date (still active).

NOTE

When a tax rate changes (e.g., the UK personal allowance is updated for a new tax year), create a new tax_rate_config record with the new effective_from_dt. Set effective_to_dt on the previous record to the day before the new rate takes effect. Never delete or modify historical rate records — they are referenced by audit snapshots.

NOTE

Pure audit columns (created_by, created_dt, updated_by, updated_dt) are omitted from the table above as they carry no business meaning beyond standard record-keeping.

2.4 `tax_calculation_audit`

Immutable audit trail for every tax calculation performed in the system. Each record captures the full input parameters, calculation results, and point-in-time snapshots of the reference data (party_tax_info and tax_rate_config) used at calculation time. This ensures that calculations can be reconstructed and verified for compliance purposes, even if the underlying reference data changes after the fact.

Field	Type	Required	Default	Description
`tax_calculation_audit_id`	`serial`	Yes	Auto	Primary key.
`context_type_cd`	`varchar(30)`	Yes	—	The processing context in which the calculation was performed. See Code Master Values for valid codes.
`context_id`	`integer`	No	—	FK to the source entity. Interpretation depends on `context_type_cd`: `SPLIT_WARNING` maps to `cash_receipt_split_id`; `WORKSHEET_PREVIEW` maps to `cash_receipt_worksheet_id`; `DEDUCTION_APPLIED` and `DEDUCTION_OVERRIDE` map to `cash_receipt_application_deduction_id`.
`input_json`	`jsonb`	No	—	Full input parameters passed to the calculation engine. Includes gross amount, commission rate, jurisdiction flags, YTD earnings, currency info, and all withholding context fields.
`result_json`	`jsonb`	No	—	Full calculation output including withholding jurisdiction, basis, rate, amount, explanation text, and any UK-specific currency conversion results.
`party_tax_info_snapshot_json`	`jsonb`	No	—	Point-in-time snapshot of the `party_tax_info` record used for this calculation. Captures residency, entity type, CWA status, treaty status, and VAT registration as they were at calculation time.
`rate_config_snapshot_json`	`jsonb`	No	—	Point-in-time snapshot of the `tax_rate_config` records used for this calculation. Captures rates and thresholds as they were at calculation time.
`calculated_by_user_id`	`integer`	No	—	FK to `users.user_id`. The user who triggered the calculation.
`calculated_dt`	`timestamp`	Yes	`now()`	Timestamp when the calculation was performed.

IMPORTANT

Audit records are write-once, never updated. Each new calculation creates a new audit record. The snapshot fields (party_tax_info_snapshot_json, rate_config_snapshot_json) are critical for compliance — they prove what data the system used at the time of calculation, independent of any subsequent changes to the source tables.

2.5 `tax_form`

Tracks individual tax forms generated by the system. Each record represents one form instance (e.g., a specific 1042-S for a specific party and tax year). Forms are generated from actual cash_receipt_application and cash_receipt_application_deduction records. The form_data_json field holds the rendered form field values, while source_map_json provides lineage tracing from each form field back to the contributing source records.

Field	Type	Required	Default	Description
`tax_form_id`	`serial`	Yes	Auto	Primary key.
`party_id`	`integer`	No	—	FK to `party.party_id`. The party this form is for (e.g., the talent receiving payment).
`party_name`	`varchar(255)`	No	—	Denormalized party name for display convenience.
`form_code_cd`	`varchar(30)`	Yes	—	Tax form type code. See Code Master Values for the complete list.
`jurisdiction_cd`	`varchar(10)`	Yes	—	Jurisdiction code: `US` or `GB`.
`tax_year`	`integer`	Yes	—	The tax year this form covers. For US forms, the calendar year. For UK forms, refers to the tax year starting on April 6.
`quarter_cd`	`varchar(5)`	No	—	Quarter designation for forms filed quarterly (HMRC FEU1/FEU2): `Q1`, `Q2`, `Q3`, `Q4`. `null` for annual forms.
`status_cd`	`varchar(20)`	Yes	`'DRAFT'`	Current form status. See Section 3.
`generated_dt`	`timestamp`	No	—	Timestamp when the form data was generated from source records.
`filed_dt`	`timestamp`	No	—	Timestamp when the form was filed with the tax authority.
`form_data_json`	`jsonb`	No	—	Snapshot of the rendered form field values at generation time. Structure varies by form type.
`source_map_json`	`jsonb`	No	—	Lineage map linking form field names to their contributing source records. Enables drill-down from calculated values to the underlying `cash_receipt_application` and `cash_receipt_application_deduction` records.
`source_type_cd`	`varchar(30)`	No	—	Source system that triggered form generation. See Code Master Values.
`source_id`	`integer`	No	—	FK to the source record (e.g., `cash_receipt_worksheet_id`).
`tax_filing_package_id`	`integer`	No	—	FK to `tax_filing_package.tax_filing_package_id`. Groups this form into a filing package for bulk submission.
`mailing_cd`	`varchar(20)`	No	—	Mailing grouping within a filing package. See Code Master Values.
`chapter_cd`	`varchar(10)`	No	—	Chapter segregation for 1042-S forms within Mailing 1. See Code Master Values.
`sequence_no`	`integer`	No	—	Ordering within a mailing. The 1042-T transmittal form is always sequence 1 in Mailing 1.
`notes`	`varchar(500)`	No	—	Free-text notes or annotations.
`created_by_user_id`	`integer`	No	—	FK to `users.user_id`. User who created the form record.
`updated_by_user_id`	`integer`	No	—	FK to `users.user_id`. User who last updated the form record.

IMPORTANT

Tax form data (form_data_json) is generated from actual cash_receipt_application and cash_receipt_application_deduction records. It is never derived from split-level references. The source_map_json field provides full lineage so that any form value can be traced back to the specific worksheet applications and deductions that contributed to it.

NOTE

Pure audit columns (created_dt, updated_dt) are omitted from the table above as they carry no business meaning beyond standard record-keeping.

2.6 `tax_filing_package`

Groups related tax forms into a cohesive filing unit for submission to a tax authority. For the IRS 1042 annual filing, a package contains two mailings: Mailing 1 (1042-T transmittal + all 1042-S Copy A forms) and Mailing 2 (Form 1042 standalone annual return). The package includes cross-form reconciliation to verify that totals across individual 1042-S forms match the summary totals on the 1042-T and 1042 forms.

Field	Type	Required	Default	Description
`tax_filing_package_id`	`serial`	Yes	Auto	Primary key. Referenced by `tax_form.tax_filing_package_id`.
`tax_year`	`integer`	Yes	—	The tax year this package covers.
`jurisdiction_cd`	`varchar(10)`	Yes	—	Jurisdiction code: `US` or `GB`.
`filing_type_cd`	`varchar(30)`	Yes	—	Filing type classification. See Code Master Values.
`status_cd`	`varchar(20)`	Yes	`'DRAFT'`	Current package status. See Section 3.
`generated_dt`	`timestamp`	No	—	Timestamp when the package was assembled.
`filed_dt`	`timestamp`	No	—	Timestamp when the package was filed with the tax authority.
`reconciliation_json`	`jsonb`	No	—	Cross-form reconciliation snapshot. Verifies that aggregate 1042-S gross and withheld amounts match the 1042-T and 1042 totals. Includes per-form breakdown and match indicators.
`notes`	`varchar(500)`	No	—	Free-text notes or annotations.
`created_by_user_id`	`integer`	No	—	FK to `users.user_id`. User who created the package.
`updated_by_user_id`	`integer`	No	—	FK to `users.user_id`. User who last updated the package.

NOTE

The reconciliation_json field captures the following verification points: totalGrossFrom1042S, totalWithheldFrom1042S, form1042TGross, form1042TWithheld, form1042Gross, form1042Withheld, grossMatch, withheldMatch, form1042Match, allReconciled, and formBreakdown (array of per-form entries with tax_form_id, party_name, gross_income, federal_tax_withheld, and chapter_cd).

NOTE

Pure audit columns (created_dt, updated_dt) are omitted from the table above as they carry no business meaning beyond standard record-keeping.

3. Status Lifecycle

3.1 `tax_form` Status

Status	Code	Description	Allowed Transitions
Draft	`DRAFT`	Form record created but data not yet generated from source records.	→ Generated (`GENERATED`)
Generated	`GENERATED`	Form data has been generated from source records. `form_data_json` and `source_map_json` are populated. Ready for review.	→ Filed (`FILED`)
Filed	`FILED`	Form has been filed with the tax authority (IRS or HMRC).	→ Submitted (`SUBMITTED`)
Submitted	`SUBMITTED`	Filing has been acknowledged or confirmed by the tax authority. Terminal state.	—

mermaid

stateDiagram-v2
    [*] --> DRAFT : Form record created
    DRAFT --> GENERATED : Generate form data
    GENERATED --> FILED : File with authority
    FILED --> SUBMITTED : Authority acknowledges

Transition: Draft → Generated

Trigger: User initiates form data generation from source records.
Preconditions: Source cash_receipt_application and cash_receipt_application_deduction records exist for the party, jurisdiction, and tax year.
Side-effects: tax_form.form_data_json populated with rendered form field values; tax_form.source_map_json populated with lineage map; tax_form.generated_dt set to current timestamp.

Transition: Generated → Filed

Trigger: User marks the form as filed after transmitting to the tax authority.
Preconditions: Form status is GENERATED and form_data_json is populated.
Side-effects: tax_form.filed_dt set to current timestamp; tax_form.status_cd set to 'FILED'.

Transition: Filed → Submitted

Trigger: User records the tax authority's acknowledgement of the filing.
Preconditions: Form status is FILED.
Side-effects: tax_form.status_cd set to 'SUBMITTED'. Terminal state — no further transitions.

3.2 `tax_filing_package` Status

Status	Code	Description	Allowed Transitions
Draft	`DRAFT`	Package created; forms may still be added or removed.	→ Generated (`GENERATED`)
Generated	`GENERATED`	All child forms have been generated and reconciliation has been computed.	→ Reviewed (`REVIEWED`)
Reviewed	`REVIEWED`	Reconciliation verified; package is approved for filing.	→ Filed (`FILED`)
Filed	`FILED`	Package has been filed with the tax authority.	→ Submitted (`SUBMITTED`)
Submitted	`SUBMITTED`	Filing has been acknowledged by the tax authority. Terminal state.	—

mermaid

stateDiagram-v2
    [*] --> DRAFT : Package created
    DRAFT --> GENERATED : Generate all forms
    GENERATED --> REVIEWED : Review reconciliation
    REVIEWED --> FILED : File with authority
    FILED --> SUBMITTED : Authority acknowledges

Transition: Draft → Generated

Trigger: User triggers generation of all forms in the package.
Preconditions: At least one tax_form record is associated with this package via tax_filing_package_id.
Side-effects: tax_filing_package.reconciliation_json computed and stored; tax_filing_package.generated_dt set to current timestamp; all associated tax_form records transition to GENERATED.

Transition: Generated → Reviewed

Trigger: User reviews reconciliation results and approves the package for filing.
Preconditions: Package status is GENERATED; reconciliation_json indicates allReconciled = true.
Side-effects: tax_filing_package.status_cd set to 'REVIEWED'.

Transition: Reviewed → Filed

Trigger: User marks the package as filed after transmitting to the tax authority.
Preconditions: Package status is REVIEWED.
Side-effects: tax_filing_package.filed_dt set to current timestamp; tax_filing_package.status_cd set to 'FILED'.

Transition: Filed → Submitted

Trigger: User records the tax authority's acknowledgement of the filing.
Preconditions: Package status is FILED.
Side-effects: tax_filing_package.status_cd set to 'SUBMITTED'. Terminal state — no further transitions.

4. Validation & Database Constraints

Unique Constraints

Table	Constraint	Columns	Business Rule
`party_tax_info`	(application-enforced)	(`party_id`, `current_item_ind`) where `current_item_ind = true`	Only one tax profile per party may be marked as current at any time. Enforced in the service layer, not at the database level in the PoC.

**PoC Artifact:**

The uniqueness of current_item_ind = true per party_id is enforced in the service layer rather than by a database partial unique index. Production should enforce this with a partial unique index: UNIQUE (party_id) WHERE current_item_ind = true.

Business Validation

Effective date non-overlap: For the same party (or the same jurisdiction + tax type), effective date ranges on party_tax_info and tax_rate_config must not overlap. Enforced in the service layer.
Audit records are write-once: tax_calculation_audit records may never be updated after creation. Each new calculation must produce a new audit row.
Snapshot completeness: When writing a tax_calculation_audit record, party_tax_info_snapshot_json and rate_config_snapshot_json must capture the full state of the reference data used — not just the fields relevant to the current calculation.
Quarter required for HMRC quarterly forms: When tax_form.jurisdiction_cd = 'GB' and form_code_cd is HMRC_FEU1 or HMRC_FEU2, quarter_cd is required.
Package consistency for child forms: When tax_form.tax_filing_package_id is set, tax_form.tax_year and tax_form.jurisdiction_cd must match the parent tax_filing_package record.
Mailing assignment: mailing_cd is only applicable when the form belongs to a filing package. 1042-T and 1042-S forms belong to MAILING_1; Form 1042 belongs to MAILING_2.
Sequence uniqueness within mailing: sequence_no must be unique within a mailing group. The 1042-T transmittal form must always be assigned sequence 1 in Mailing 1.
CWA amount required when CWA active: When has_cwa_approval_ind = true, cwa_withholding_amt must be configured and greater than zero. If null or zero, the system raises a compliance alert rather than silently applying $0 withholding.
VAT number required when VAT registered: When vat_registered_ind = true, vat_number must be provided for compliance reporting.
Historical records are immutable: Once effective_to_dt has been set on a party_tax_info or tax_rate_config record, that record must not be modified. Changes are captured by creating a new effective-dated version.

5. Code Master Values

5.1 Entity Type Codes (`party_tax_info.entity_type_cd`)

Code	Description	Behavior / When Used
`INDIVIDUAL`	Natural person / individual	Used for talent represented as themselves.
`CORPORATION`	Corporate entity	Used for corporate payees.
`LOAN_OUT`	Loan-out company	Entity through which talent routes income. Withholding is assessed at the entity level.

Default on creation: None — must be set explicitly.

5.2 TIN Type Codes (`party_tax_info.tin_type_cd`)

Code	Description	Behavior / When Used
`SSN`	Social Security Number	US individuals. Required for 1099-NEC reporting.
`EIN`	Employer Identification Number	US entities and loan-out companies.
`UTR`	Unique Taxpayer Reference	UK individuals and entities. Required for HMRC FEU forms.
`NIN`	National Insurance Number	UK individuals.
`SIN`	Social Insurance Number	Canadian payees.

Default on creation: None — must be set explicitly.

5.3 W-8 Form Type Codes (`party_tax_info.w8_form_type_cd`)

Code	Description	Behavior / When Used
`W8_BEN`	Certificate of Foreign Status of Beneficial Owner (individuals)	Non-resident alien individuals receiving US-source income.
`W8_BEN_E`	Certificate of Status of Beneficial Owner (entities)	Foreign entities receiving US-source income.
`W8_ECI`	Certificate of Foreign Person's Claim for Effectively Connected Income	Effectively connected income scenarios.

Default on creation: None — must be set explicitly.

5.4 Tax Type Codes (`tax_rate_config.tax_type_cd`)

Code	Description	Behavior / When Used
`WITHHOLDING_NRA`	Non-resident alien withholding rate	Applied at 30% on US-source income paid to non-resident aliens without a CWA or treaty exemption.
`WITHHOLDING_FEU`	Foreign Entertainers Unit withholding rate	Applied at 20% on UK earnings exceeding the personal allowance threshold.
`PERSONAL_ALLOWANCE`	UK personal allowance threshold	Stored in `threshold_amt` (not `rate`). Currently `12570.00 GBP`. Determines when FEU withholding activates.
`VAT_ARTIST_FEE`	VAT rate applied to artist fees	20% on artist fee for UK Agency + UK Show + UK Client + VAT-registered talent.
`VAT_COMMISSION`	VAT rate applied to agency commission	20% on commission for UK Agency + UK Client transactions.

Default on creation: None — records are seeded by administrators.

5.5 Tax Form Codes (`tax_form.form_code_cd`)

Code	Description	Behavior / When Used
`IRS_1042_S`	Foreign Person's US Source Income Subject to Withholding	Annual. Generated per non-resident alien payee receiving US-source income.
`IRS_1042`	Annual Withholding Tax Return for US Source Income	Annual. Summary return filed by the withholding agent (UTA).
`IRS_1042_T`	Annual Summary and Transmittal of Forms 1042-S	Annual. Transmittal form bundled with 1042-S Copy A forms in Mailing 1.
`IRS_1099_NEC`	Nonemployee Compensation	Annual. Filed for US residents with `has_w9_on_file_ind = true`.
`IRS_CWA_Approval`	Central Withholding Agreement Approval	Per engagement. Documents the IRS-approved CWA for a specific engagement.
`HMRC_FEU1`	Quarterly Return of Income Tax on Payments to Foreign Entertainers	Quarterly. Requires `quarter_cd`.
`HMRC_FEU2`	Certificate of Tax Deducted from Payment to Foreign Entertainer	Quarterly. Requires `quarter_cd`.
`HMRC_VAT_RETURN`	Quarterly VAT Return	Quarterly. Filed when UK VAT has been collected.
`CRA_T4A_NR`	Statement of Fees, Commissions, or Other Amounts Paid to Non-Residents	Annual. Filed for Canadian non-resident payees.

Default on creation: None — set at form creation time.

5.6 `TAX_FORM_STATUS_CD` (`tax_form.status_cd`)

Code	Description	Behavior / When Used
`DRAFT`	Form record created; data not yet generated	Default on creation. No `form_data_json` populated yet.
`GENERATED`	Form data generated from source records; ready for review	`form_data_json` and `source_map_json` are populated; `generated_dt` is set.
`FILED`	Filed with tax authority	`filed_dt` is set.
`SUBMITTED`	Acknowledged by tax authority	Terminal state. No further transitions.

Default on creation: DRAFT

5.7 `TAX_FILING_PACKAGE_STATUS_CD` (`tax_filing_package.status_cd`)

Code	Description	Behavior / When Used
`DRAFT`	Package created; forms may still be added	Default on creation.
`GENERATED`	All forms generated; reconciliation computed	`reconciliation_json` is populated; `generated_dt` is set.
`REVIEWED`	Reconciliation verified; approved for filing	Package confirmed ready for submission.
`FILED`	Filed with tax authority	`filed_dt` is set.
`SUBMITTED`	Acknowledged by tax authority	Terminal state. No further transitions.

Default on creation: DRAFT

5.8 Filing Type Codes (`tax_filing_package.filing_type_cd`)

Code	Description	Behavior / When Used
`IRS_1042_ANNUAL`	IRS annual 1042 filing package	Groups Mailing 1 (1042-T + 1042-S Copy A forms) and Mailing 2 (Form 1042 annual return).

Default on creation: None — set at package creation time.

5.9 Mailing Codes (`tax_form.mailing_cd`)

Code	Description	Behavior / When Used
`MAILING_1`	First mailing in 1042 annual filing	Contains 1042-T transmittal (sequence 1) + all 1042-S Copy A forms.
`MAILING_2`	Second mailing in 1042 annual filing	Contains Form 1042 standalone annual return.

Default on creation: None — assigned when the form is added to a filing package.

5.10 Chapter Codes (`tax_form.chapter_cd`)

Code	Description	Behavior / When Used
`CH3_ORIG`	Chapter 3 original	Original 1042-S forms filed under Chapter 3 withholding rules.
`CH4_ORIG`	Chapter 4 original	Original 1042-S forms filed under Chapter 4 (FATCA) rules.
`AMENDED`	Amended	Amended 1042-S forms replacing previously filed originals.

Default on creation: None — assigned during form classification.

5.11 Tax Calculation Context Type Codes (`tax_calculation_audit.context_type_cd`)

Code	Description	Behavior / When Used
`SPLIT_WARNING`	Tax warning at split level	Calculated when a party reference is added to a `cash_receipt_split`. `context_id` = `cash_receipt_split_id`.
`WORKSHEET_PREVIEW`	Tax preview on worksheet	Tax preview shown on the receivables table within a worksheet. `context_id` = `cash_receipt_worksheet_id`.
`DEDUCTION_APPLIED`	Tax deduction applied	Tax deduction applied via a billing item deduction record. `context_id` = `cash_receipt_application_deduction_id`.
`DEDUCTION_OVERRIDE`	User overrode tax amount	User manually overrode the system-calculated tax amount. `context_id` = `cash_receipt_application_deduction_id`.

Default on creation: None — set by the tax calculation engine at the time of calculation.

5.12 Tax Form Source Type Codes (`tax_form.source_type_cd`)

Code	Description	Behavior / When Used
`TAX_SCENARIO`	Form generated from tax scenario evaluation	Used during requirements modeling (PoC tool only; not production-facing).
`WORKSHEET`	Form generated from worksheet application data	Production source — form data derived from actual `cash_receipt_application` records.
`MANUAL`	Form manually created by a user	Direct creation without a system-generated source.

Default on creation: None — set at form creation time.

5.13 UK Tax Year Quarter Codes (`tax_form.quarter_cd`)

Code	Description	Behavior / When Used
`Q1`	April 6 – June 30	HMRC FEU1/FEU2 due July 14.
`Q2`	July 1 – September 30	HMRC FEU1/FEU2 due October 14.
`Q3`	October 1 – December 31	HMRC FEU1/FEU2 due January 14.
`Q4`	January 1 – April 5	HMRC FEU1/FEU2 due April 19.

Default on creation: None — required for HMRC quarterly forms; null for annual forms.

IMPORTANT

The UK tax year runs from April 6 to April 5, not the calendar year. The tax_year field on HMRC forms refers to the year in which the tax year starts (e.g., tax_year = 2025 covers April 6, 2025 through April 5, 2026).

6. Cross-References

Document	Relationship
Parties Data Model	`party_tax_info.party_id` and `tax_form.party_id` → `party.party_id`. The party record identifies the talent, client, or payee whose tax profile is maintained.
Billing Items Data Model	Tax withholding is calculated against billing item details (REV/PAY). `billing_item.client_id` and `billing_item.uta_entity_id` drive tax jurisdiction determination. Tax is derived from the billing item, not from split references.
Worksheets Data Model	The worksheet is where tax calculations are surfaced (preview badges on receivable rows, tax summary in headers) and where deductions are applied. `tax_calculation_audit.context_id` references `cash_receipt_worksheet_id` for `WORKSHEET_PREVIEW` context.
Cash Receipts Data Model	Split-level party references trigger early tax warnings (`SPLIT_WARNING` context in `tax_calculation_audit`). `tax_calculation_audit.context_id` references `cash_receipt_split_id` for `SPLIT_WARNING` context. Split references are informational only — they do not drive worksheet-level tax calculations.
Worksheets Data Model	Tax withholding amounts are recorded as `cash_receipt_application_deduction` records. These deduction records are the source data for tax form generation via `source_map_json`.

Sample Deals

Touring Deal

Endorsement Deal

Sports Endo Deal

Tax Withholding Data Model ​

1. Executive Summary ​

Purpose ​

Scope ​

2. Data Model ​

2.1 Entity-Relationship Diagram ​

2.2 party_tax_info ​

2.3 tax_rate_config ​

2.4 tax_calculation_audit ​

2.5 tax_form ​

2.6 tax_filing_package ​

3. Status Lifecycle ​

3.1 tax_form Status ​

Transition: Draft → Generated ​

Transition: Generated → Filed ​

Transition: Filed → Submitted ​

3.2 tax_filing_package Status ​

Transition: Draft → Generated ​

Transition: Generated → Reviewed ​

Transition: Reviewed → Filed ​

Transition: Filed → Submitted ​

4. Validation & Database Constraints ​

Unique Constraints ​

Business Validation ​

5. Code Master Values ​

5.1 Entity Type Codes (party_tax_info.entity_type_cd) ​

5.2 TIN Type Codes (party_tax_info.tin_type_cd) ​

5.3 W-8 Form Type Codes (party_tax_info.w8_form_type_cd) ​

5.4 Tax Type Codes (tax_rate_config.tax_type_cd) ​

5.5 Tax Form Codes (tax_form.form_code_cd) ​

5.6 TAX_FORM_STATUS_CD (tax_form.status_cd) ​

5.7 TAX_FILING_PACKAGE_STATUS_CD (tax_filing_package.status_cd) ​

5.8 Filing Type Codes (tax_filing_package.filing_type_cd) ​

5.9 Mailing Codes (tax_form.mailing_cd) ​

5.10 Chapter Codes (tax_form.chapter_cd) ​

5.11 Tax Calculation Context Type Codes (tax_calculation_audit.context_type_cd) ​

5.12 Tax Form Source Type Codes (tax_form.source_type_cd) ​

5.13 UK Tax Year Quarter Codes (tax_form.quarter_cd) ​

6. Cross-References ​

Tax Withholding Data Model

1. Executive Summary

Purpose

Scope

2. Data Model

2.1 Entity-Relationship Diagram

2.2 `party_tax_info`

2.3 `tax_rate_config`

2.4 `tax_calculation_audit`

2.5 `tax_form`

2.6 `tax_filing_package`

3. Status Lifecycle

3.1 `tax_form` Status

Transition: Draft → Generated

Transition: Generated → Filed

Transition: Filed → Submitted

3.2 `tax_filing_package` Status

Transition: Draft → Generated

Transition: Generated → Reviewed

Transition: Reviewed → Filed

Transition: Filed → Submitted

4. Validation & Database Constraints

Unique Constraints

Business Validation

5. Code Master Values

5.1 Entity Type Codes (`party_tax_info.entity_type_cd`)

5.2 TIN Type Codes (`party_tax_info.tin_type_cd`)

5.3 W-8 Form Type Codes (`party_tax_info.w8_form_type_cd`)

5.4 Tax Type Codes (`tax_rate_config.tax_type_cd`)

5.5 Tax Form Codes (`tax_form.form_code_cd`)

5.6 `TAX_FORM_STATUS_CD` (`tax_form.status_cd`)

5.7 `TAX_FILING_PACKAGE_STATUS_CD` (`tax_filing_package.status_cd`)

5.8 Filing Type Codes (`tax_filing_package.filing_type_cd`)

5.9 Mailing Codes (`tax_form.mailing_cd`)

5.10 Chapter Codes (`tax_form.chapter_cd`)

5.11 Tax Calculation Context Type Codes (`tax_calculation_audit.context_type_cd`)

5.12 Tax Form Source Type Codes (`tax_form.source_type_cd`)

5.13 UK Tax Year Quarter Codes (`tax_form.quarter_cd`)

6. Cross-References