Clarify that calibration is required (not just recommended) for pKa

[galjos]

Found by running real xtb-cli calculations on the pKa helper from #115, the same "test with real data" pattern used for the QM-import engines this session.

The finding

The docs said the raw direct-method pKa has "several-pKa-unit systematic error" (citing DFT+continuum-solvent literature) and suggested calibration for "quantitative accuracy." Running it for real on GFN2-xTB (phenol/phenolate, water) tells a very different story: the raw pKa comes out at ≈-100 against the experimental 9.99 — an error of ~110 pKa units, not "several."

This isn't a bug — I verified the arithmetic is internally self-consistent (the ~150 kcal/mol calibration shift needed exactly accounts for the gap). It's a real, well-known property of semiempirical tight-binding methods: they don't preserve an absolute ab-initio/experimental energy scale, so mixing their electronic energies directly with a literature constant derived assuming DFT/ab-initio-quality absolute energies is fundamentally invalid — not just imprecise.

Calibrating against one reference compound completely fixes this (it's a molecule-independent additive offset): hydroquinone calibrated against phenol (pKa_exp = 9.99) came out at 11.00 vs. the experimental 10.35 — a good result for a cheap semiempirical method.

The fix

• pka.py: strengthen the Notes sections — calibration is required, not merely recommended, for GFN-xTB/DFTB, with the real verified numbers.
• docs/usage.rst: replace the old placeholder calibration example (calibrate_proton_reference(ref_acid, ref_base, experimental_pKa=4.20), using undefined variables — not even runnable) with this real, working, verified phenol/hydroquinone example.
• Tests: a skippable real-xtb-cli integration test reproducing both numbers end to end, gated on the native xtb binary (matching test_reactions.py's existing pattern).

Verification

Ran locally with the real xtb binary: 10/10 tests pass including the new real-engine test. Full suite: 391 passed, 13 skipped (correctly gated when xtb is absent). 100% patch coverage. Docs build clean.

Closes #116

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.31%. Comparing base (17fa876) to head (6eb7810).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #117   +/-   ##
=======================================
  Coverage   97.31%   97.31%           
=======================================
  Files          32       32           
  Lines        1935     1935           
=======================================
  Hits         1883     1883           
  Misses         52       52           

Flag	Coverage Δ
unittests	97.31% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.