Document that inverting `pair_coalescence_rate` should account for factor of 2 to match diploid Ne

[hyanwong]

Diploid Ne is given by 1/(2*pair_coalescence_rate). Although the pair_coalescence_rate implementation is consistent with msprime.DemographyDebugger, it's different from things like PSMC or MSMC that encourage users to interpret things in terms of diploid pop size. It would be helpful to document this in a .. note:: in the docstring.