You got this one backwards. A hyper-threaded processor, advertised as, say, having 8 cores and 16 threads (2 threads per core) has 8 physical cores, but 16 logical cores, i.e. “hardware threads”. A Linux system will mostly report this as “16 cores”, without distinction. htop will show individual load for 16 cores, /proc/cpuinfo will list 16 cores. See also this question.
My understanding is that this refers to the fact that certain compilers or compiling certain codebases may not produce bit-for-bit identical output, or compilation may outright fail when you allow them to compile several parts of the code in parallel, but will produce a consistent result if you compile stuff sequentially.
enableParallelBuilding seems to be the default for any package that uses stdenv (which is the majority of packages in nixpkgs). Notably, this issue lists a bunch of issues that were previously present when building certain packages in parallel. You can also use GitHub code search to find packages where parallel building is still explicitly disabled due to issues.
I think the documentation you linked is pretty clear. max-jobs defines how many derivations will be built in parallel (at the same time) - the Nix daemon itself takes care of this. cores defines how many “cores” may be utilized while building each one of those derivations, and it is up to the derivation to respect this (e.g. by running make -j$NIX_BUILD_CORES - the cores setting is exposed to the derivation as the NIX_BUILD_CORES environment variable).
The funny thing I realized is that NixOS sets both max-jobs and cores to auto or 0, meaning they will both default default to the number of logical cores. So for a CPU with 16 threads you will potentially have 16 * 16 = 256 build processes. There’s been discussion about improving this, but there’s no consensus yet, it seems.
Looks like max-substitution-jobs is what you need. I don’t blame you for not immediately realizing that substitute roughly means “download from a cache” in Nix land.