docs: state the 15 % fuel reserve and the mass-estimate iterations as the code runs them

docs/explanation/input-prioritization.md

@@ -57,7 +57,7 @@ $$
 
 **Step 2 — Compute fuel flow** and fuel burn at each trajectory point using BADA.
 
-**Step 3 — Estimate fuel reserve** (≈ 3 % of trip fuel).
+**Step 3 — Estimate fuel reserve:** 15 % of trip fuel (`fuel_reserve_fraction`, following Teoh et al., 2024).
 
 **Step 4 — Update TOW:**
 
@@ -67,7 +67,7 @@ $$
 
 Reduce aircraft mass along the trajectory according to fuel burnt at each point.
 
-**Step 5 — Iterate** steps 2–4 until convergence. In PyNeats, **two iterations** are used to balance accuracy and computational cost.
+**Step 5 — Iterate** steps 2–4, with the mass now starting at the updated TOW and decreasing along the trajectory, until the TOW changes by 1 % or less of the previous TOW (`max_rel_mass_diff`). Within one estimate, steps 2–4 run at least twice and at most four times (`max_mass_estimation_iter`); after the fourth time the result is kept even if the change is still above 1 %. A retry with BADA 3, or after points below FL20 are removed, starts the estimate again from step 1. The fuel flow, thrust and mass kept are those of the last BADA calculation, which started from the TOW of the previous update; the TOW computed after that calculation is used only for the convergence test.
 
 !!! info "MPL source"
     MPL (Maximum Payload) is read from the BADA files: the OPF maximum payload for BADA 3, the aircraft file for BADA 4. Only if a BADA file gives no MPL is $\text{MPL} = MTOW - OEW$ used.

docs/explanation/mrv-specification.md

@@ -200,7 +200,7 @@ The following rules are applied **sequentially** to determine how the primary da
 
     2. **First performance calculation:** compute fuel flow and fuel burn at each trajectory point from this mass.
 
-    3. **Fuel-reserve estimation:** the required reserve is approximated at **3 % of trip fuel**.
+    3. **Fuel-reserve estimation:** the required reserve is **15 % of trip fuel** (`fuel_reserve_fraction`, following Teoh et al., 2024).
 
     4. **Updated TOW:**
 
@@ -211,7 +211,7 @@ The following rules are applied **sequentially** to determine how the primary da
         !!! note "MPL source"
             MPL is read from the BADA files (the OPF maximum payload for BADA 3). Only if a BADA file gives no MPL is $\text{MPL} = MTOW - OEW$ used.
 
-    5. **Iteration:** steps 2–4 are repeated until convergence (fixed number of iterations, or relative-tolerance stopping criterion). In PyNeats, **steps 2–4 are performed twice** to reduce computational effort.
+    5. **Iteration:** steps 2–4 are repeated, with the mass along the trajectory now starting at the updated TOW, until the TOW changes by 1 % or less of the previous TOW (`max_rel_mass_diff`). Within one estimate, steps 2–4 run at least twice and at most four times (`max_mass_estimation_iter`); after the fourth time the result is kept even if the change is still above 1 %. A retry with BADA 3, or after points below FL20 are removed, starts the estimate again from step 1. The fuel flow, thrust and mass kept are those of the last BADA calculation, which started from the TOW of the previous update; the TOW computed after that calculation is used only for the convergence test.
 
 See [Input Prioritization](input-prioritization.md) for the full decision flowchart.
 

docs/internal/pyneats_units_audit.md

@@ -14,7 +14,8 @@ note under its item. Items not listed here are open.
 | D2 (trajectory `ts` offsets) | Fixed | #70 | 2026-10-20 |
 | One flight that cannot be converted no longer stops the run (D2 follow-up) | Fixed | #71 | 2026-10-20 |
 | D1 (bare single-flight object) | Open; now a clear `TypeError` on the `FleetRunner` JSON path | #71 | 2026-10-20 |
-| I4 (BADA3 maximum payload) | Fixed; changes BADA3 fuel and CO2 | `fix/bada3-max-payload` | 2026-10-21 |
+| I4 (BADA3 maximum payload) | Fixed; changes BADA3 fuel and CO2 | #73 | 2026-10-21 |
+| Fuel reserve and number of mass iterations misstated in the user docs (Section 9) | Fixed (docs only) | `docs/fuel-reserve-15pct` | 2026-10-21 |
 
 ## 1. Outcome
 
@@ -707,6 +708,8 @@ discrepancies:
 | `docs/internal/performance_use_cases_analysis.md` | TAS always recomputed; early exit on FF+EE; FF never derived from mass | TAS kept when provided; early exit needs FF+EE+AM; FF derived from AM | mark superseded |
 | `scripts/parquet_to_neats_json.py` | treats `altitude` as feet and stamps `+0000` without converting | basis (barometric or geometric) and time zone unverified | document expected input |
 | `tests/test_performance_fallback.py:4,74,80`; `tests/test_guardrails.py:133,142,151` | FL15; 500 hPa | FL20; 550 hPa | update test docstrings |
+| `docs/explanation/input-prioritization.md:60`; `docs/explanation/mrv-specification.md:203` | initial-mass fuel reserve ≈ 3 % of trip fuel | 15 % (`DEFAULT_FUEL_RESERVE_FRACTION = 0.15`, `neats_default_parameters.py:148`; `bada_model.py:1058`). Found after this audit, during the I4 review | fixed (`docs/fuel-reserve-15pct`) |
+| `docs/explanation/input-prioritization.md:70`; `docs/explanation/mrv-specification.md:214` | the mass estimate runs steps 2–4 "twice" | when neither an `aircraft_mass` column nor a `takeoff_weight` attribute is given, steps 2–4 run at least twice and at most four times per estimate: one constant-mass BADA pass, then up to three passes from the updated TOW, stopping when the TOW changes by ≤ 1 % of the previous TOW (`max_mass_estimation_iter = 4`, `max_rel_mass_diff = 0.01`, `bada_model.py:1065-1117`); the last pass is kept. Measured on the 4,303 flights computed from the NEATS_FINAL sample: 2,769 stop after two passes, 1,415 after three, 119 after four, 3 of which stop at the cap with a change of 1.0–1.4 % (1.04, 1.17 and 1.39 %) | fixed (`docs/fuel-reserve-15pct`) |
 
 ## 10. Incidental observations outside the unit scope